home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2005 October / PCWOCT05.iso / Software / FromTheMag / XAMPP 1.4.14 / xampp-win32-1.4.14-installer.exe / xampp / php / pear / Cache.php < prev    next >
PHP Script  |  2004-10-01  |  11KB  |  357 lines
  1. <?php
  2. // +----------------------------------------------------------------------+
  3. // | PEAR :: Cache                                                        |
  4. // +----------------------------------------------------------------------+
  5. // | Copyright (c) 1997-2003 The PHP Group                                |
  6. // +----------------------------------------------------------------------+
  7. // | This source file is subject to version 2.0 of the PHP license,       |
  8. // | that is bundled with this package in the file LICENSE, and is        |
  9. // | available at through the world-wide-web at                           |
  10. // | http://www.php.net/license/2_02.txt.                                 |
  11. // | If you did not receive a copy of the PHP license and are unable to   |
  12. // | obtain it through the world-wide-web, please send a note to          |
  13. // | license@php.net so we can mail you a copy immediately.               |
  14. // +----------------------------------------------------------------------+
  15. // | Authors: Ulf Wendel <ulf.wendel@phpdoc.de>                           |
  16. // |          Sebastian Bergmann <sb@sebastian-bergmann.de>               |
  17. // +----------------------------------------------------------------------+
  18. //
  19. // $Id: Cache.php,v 1.5 2003/01/04 11:54:45 mj Exp $
  20.  
  21. require_once 'PEAR.php';
  22. require_once 'Cache/Error.php';
  23.  
  24. /**
  25. * Cache is a base class for cache implementations.
  26. *
  27. * The pear cache module is a generic data cache which can be used to 
  28. * cache script runs. The idea behind the cache is quite simple. If you have
  29. * the same input parameters for whatever tasks/algorithm you use you'll
  30. * usually get the same output. So why not caching templates, functions calls,
  31. * graphic generation etc. Caching certain actions e.g. XSLT tranformations
  32. * saves you lots of time. 
  33. *
  34. * The design of the cache reminds of PHPLibs session implementation. A 
  35. * (PHPLib: session) controller uses storage container (PHPLib: ct_*.inc) to save 
  36. * certain data (PHPLib: session data). In contrast to the session stuff it's up to 
  37. * you to generate an ID for the data to cache. If you're using the output cache
  38. * you might use the script name as a seed for cache::generateID(), if your using the
  39. * function cache you'd use an array with all function parameters.
  40. *
  41. * Usage example of the generic data cache:
  42. *
  43. * require_once('Cache.php');
  44. *
  45. * $cache = new Cache('file', array('cache_dir' => 'cache/') );
  46. * $id = $cache->generateID('testentry');
  47. *
  48. * if ($data = $cache->get($id)) {
  49. *    print "Cache hit.<br>Data: $data";
  50. *
  51. * } else {
  52. *   $data = 'data of any kind';
  53. *   $cache->save($id, $data);
  54. *   print 'Cache miss.<br>';
  55. * }
  56. *
  57. * WARNING: No File/DB-Table-Row locking is implemented yet,
  58. *          it's possible, that you get corrupted data-entries under
  59. *          bad circumstances  (especially with the file container)
  60. *
  61. * @author   Ulf Wendel <ulf.wendel@phpdoc.de>
  62. * @version  $Id: Cache.php,v 1.5 2003/01/04 11:54:45 mj Exp $
  63. * @package  Cache
  64. * @access   public
  65. */
  66. class Cache extends PEAR {
  67.  
  68.     /**
  69.     * Enables / disables caching.
  70.     *
  71.     * TODO: Add explanation what this is good for.
  72.     *
  73.     * @var      boolean
  74.     * @access   private
  75.     */
  76.     var $caching = true;
  77.  
  78.     /**
  79.     * Garbage collection: probability in seconds
  80.     *
  81.     * If set to a value above 0 a garbage collection will
  82.     * flush all cache entries older than the specified number
  83.     * of seconds.
  84.     *
  85.     * @var      integer
  86.     * @see      $gc_probability, $gc_maxlifetime
  87.     * @access   public
  88.     */
  89.     var $gc_time  = 1;
  90.  
  91.     /**
  92.     * Garbage collection: probability in percent
  93.     *
  94.     * TODO: Add an explanation.
  95.     *
  96.     * @var      integer     0 => never
  97.     * @see      $gc_time, $gc_maxlifetime
  98.     * @access   public
  99.     */
  100.     var $gc_probability = 1;
  101.     
  102.     /**
  103.     * Garbage collection: delete all entries not use for n seconds.
  104.     *
  105.     * Default is one day, 60 * 60 * 24 = 86400 seconds.
  106.     *
  107.     * @var  integer
  108.     * @see  $gc_probability, $gc_time
  109.     */
  110.     var $gc_maxlifetime = 86400;
  111.  
  112.     /**
  113.     * Storage container object.
  114.     *
  115.     * @var  object Cache_Container
  116.     */
  117.     var $container;
  118.  
  119.     //
  120.     // public methods
  121.     //
  122.  
  123.     /**
  124.     *
  125.     * @param    string  Name of container class
  126.     * @param    array   Array with container class options
  127.     */
  128.     function Cache($container, $container_options = '')
  129.     {
  130.         $this->PEAR();
  131.         $container = strtolower($container);
  132.         $container_class = 'Cache_Container_' . $container;
  133.         $container_classfile = 'Cache/Container/' . $container . '.php';
  134.  
  135.         include_once $container_classfile;
  136.         $this->container = new $container_class($container_options);
  137.     }
  138.  
  139.     //deconstructor
  140.     function _Cache()
  141.     {
  142.         $this->garbageCollection();
  143.     }
  144.  
  145.     /**
  146.      * Returns the current caching state.
  147.      *
  148.      * @return  boolean     The current caching state.
  149.      * @access  public
  150.      */
  151.     function getCaching()
  152.     {
  153.         return ($this->caching);
  154.     }
  155.  
  156.     /**
  157.      * Enables or disables caching.
  158.      *
  159.      * @param   boolean     The new caching state.
  160.      * @access  public
  161.      */
  162.     function setCaching($state)
  163.     {
  164.         $this->caching = $state;
  165.     }
  166.  
  167.     /**
  168.     * Returns the requested dataset it if exists and is not expired
  169.     *
  170.     * @param    string  dataset ID
  171.     * @param    string  cache group
  172.     * @return   mixed   cached data or NULL on failure
  173.     * @access   public
  174.     */
  175.     function get($id, $group = 'default') {
  176.         if (!$this->caching)
  177.             return '';
  178.  
  179.         if ($this->isCached($id, $group) && !$this->isExpired($id, $group))
  180.             return $this->load($id, $group);
  181.  
  182.         return NULL;
  183.     } // end func get
  184.  
  185.     /**
  186.     * Stores the given data in the cache.
  187.     *
  188.     * @param    string  dataset ID used as cache identifier
  189.     * @param    mixed   data to cache
  190.     * @param    integer lifetime of the cached data in seconds - 0 for endless
  191.     * @param    string  cache group
  192.     * @return   boolean
  193.     * @access   public
  194.     */
  195.     function save($id, $data, $expires = 0, $group = 'default') {
  196.         if (!$this->caching)
  197.             return true;
  198.  
  199.         return $this->extSave($id, $data, '',$expires, $group);
  200.     } // end func save
  201.  
  202.     /**
  203.     * Stores a dataset with additional userdefined data.
  204.     *
  205.     * @param    string  dataset ID
  206.     * @param    mixed   data to store
  207.     * @param    string  additional userdefined data
  208.     * @param    mixed   userdefined expire date
  209.     * @param    string  cache group
  210.     * @return   boolean
  211.     * @throws   Cache_Error
  212.     * @access   public
  213.     * @see      getUserdata()
  214.     */
  215.     function extSave($id, $cachedata, $userdata, $expires = 0, $group = 'default') {
  216.         if (!$this->caching)
  217.             return true;
  218.  
  219.         return $this->container->save($id, $cachedata, $expires, $group, $userdata);
  220.     } // end func extSave
  221.  
  222.     /**
  223.     * Loads the given ID from the cache.
  224.     *
  225.     * @param    string  dataset ID
  226.     * @param    string  cache group
  227.     * @return   mixed   cached data or NULL on failure
  228.     * @access   public
  229.     */
  230.     function load($id, $group = 'default') {
  231.         if (!$this->caching)
  232.             return '';
  233.  
  234.         return $this->container->load($id, $group);
  235.     } // end func load
  236.  
  237.     /**
  238.     * Returns the userdata field of a cached data set.
  239.     *
  240.     * @param    string  dataset ID
  241.     * @param    string  cache group
  242.     * @return   string  userdata
  243.     * @access   public
  244.     * @see      extSave()
  245.     */
  246.     function getUserdata($id, $group = 'default') {
  247.         if (!$this->caching)
  248.             return '';
  249.  
  250.         return $this->container->getUserdata($id, $group);
  251.     } // end func getUserdata
  252.  
  253.     /**
  254.     * Removes the specified dataset from the cache.
  255.     *
  256.     * @param    string  dataset ID
  257.     * @param    string  cache group
  258.     * @return   boolean
  259.     * @access   public
  260.     */
  261.     function remove($id, $group = 'default') {
  262.         if (!$this->caching)
  263.             return true;
  264.  
  265.         return $this->container->remove($id, $group);
  266.     } // end func remove
  267.  
  268.     /**
  269.     * Flushes the cache - removes all data from it
  270.     *
  271.     * @param    string  cache group, if empty all groups will be flashed
  272.     * @return   integer number of removed datasets
  273.     */
  274.     function flush($group = 'default') {
  275.         if (!$this->caching)
  276.             return true;
  277.  
  278.         return $this->container->flush($group);
  279.     } // end func flush
  280.  
  281.     /**
  282.     * Checks if a dataset exists.
  283.     *
  284.     * Note: this does not say that the cached data is not expired!
  285.     *
  286.     * @param    string  dataset ID
  287.     * @param    string  cache group
  288.     * @return   boolean
  289.     * @access   public
  290.     */
  291.     function isCached($id, $group = 'default') {
  292.         if (!$this->caching)
  293.             return false;
  294.  
  295.         return $this->container->isCached($id, $group);
  296.     } // end func isCached
  297.  
  298.     /**
  299.     * Checks if a dataset is expired
  300.     *
  301.     * @param    string  dataset ID
  302.     * @param    string  cache group
  303.     * @param    integer maximum age for the cached data in seconds - 0 for endless
  304.     *                   If the cached data is older but the given lifetime it will
  305.     *                   be removed from the cache. You don't have to provide this
  306.     *                   argument if you call isExpired(). Every dataset knows
  307.     *                   it's expire date and will be removed automatically. Use
  308.     *                   this only if you know what you're doing...
  309.     * @return   boolean
  310.     * @access   public
  311.     */
  312.     function isExpired($id, $group = 'default', $max_age = 0) {
  313.         if (!$this->caching)
  314.             return true;
  315.  
  316.         return $this->container->isExpired($id, $group, $max_age);
  317.     } // end func isExpired
  318.  
  319.     /**
  320.     * Generates a "unique" ID for the given value
  321.     *
  322.     * This is a quick but dirty hack to get a "unique" ID for a any kind of variable.
  323.     * ID clashes might occur from time to time although they are extreme unlikely!
  324.     *
  325.     * @param    mixed   variable to generate a ID for
  326.     * @return   string  "unique" ID
  327.     * @access   public
  328.     */
  329.     function generateID($variable) {
  330.         // WARNING: ID clashes are possible although unlikely
  331.         return md5(serialize($variable));
  332.     }
  333.  
  334.     /**
  335.     * Calls the garbage collector of the storage object with a certain probability
  336.     *
  337.     * @param    boolean Force a garbage collection run?
  338.     * @see  $gc_probability, $gc_time
  339.     */
  340.     function garbageCollection($force = false) {
  341.         static $last_run = 0;
  342.  
  343.         if (!$this->caching)
  344.             return;
  345.  
  346.         srand((double) microtime() * 1000000);
  347.  
  348.         // time and probability based
  349.         if (($force) || ($last_run && $last_run < time() + $this->gc_time) || (rand(1, 100) < $this->gc_probability)) {
  350.             $this->container->garbageCollection($this->gc_maxlifetime);
  351.             $last_run = time();
  352.         }
  353.     } // end func garbageCollection
  354.  
  355. } // end class cache
  356. ?>
  357.